Refs #642 (closed as docs-issue-not-codegen-bug after audit).

Problem

Several entity names appear in multiple spec slices as genuinely different shapes — `Creative` (full metadata in listing, 6-field shape in delivery, separate variant in sync result), `Package` (canonical vs response shape), `MediaBuy` (canonical vs capability declaration vs response), `Deployment` (RootModel wrapper vs structured `Deployment1`), and the `Geo*ExcludeItem` mirrors of `GeoCountry` etc.

Top-level imports like `from adcp import Creative` resolve to a single variant — typically the delivery-side one — silently. Adopters subclassing this for use in `ListCreativesResponse.creatives` get a class that constructs fine but trips `mypy [assignment]` and may silently drop fields the response expected.

What this PR does

Adds a new section "Picking the Right Base Class — Context-Specific Schema Variants" at the top of `docs/extending-types.md` covering:

1. A lookup table of the common cases with the correct submodule import path. For each: which response slice uses it, what to import, what NOT to import (and what would resolve incorrectly).
2. How adopters detect a wrong import — mypy under `--strict` flags `[assignment]` on the response override. The diagnostic-walk shows the right import switches the type to the parent's expected element type.
3. When the override is genuinely cross-class (e.g. `GeoExcludeItem` vs `Geo` inclusion variants — shape-identical but distinct classes) the type:ignore is warranted; document it instead of fighting mypy.
4. Forward pointer to the spec rename tracker adcontextprotocol/adcp#4347.

Also updates two existing examples in the same guide that imported `Creative` from the top-level `adcp` namespace to use the listing-slice path explicitly, matching the new guidance.

Source of the cases

This guidance is derived from production usage in bokelley/salesagent, the most-advanced Python adopter. The audit traced every `# type: ignore[assignment]` in the salesagent schema package and identified which were genuine inheritance gaps (PR #640 `Sequence[X]` covers those) vs. cross-class confusion (this docs PR addresses those).

What this PR doesn't fix

The underlying friction — that adopters need to know spec slices to navigate imports — is a spec-level concern, tracked in adcontextprotocol/adcp#4347. When the rename ships, several of the cases in the lookup table dissolve. The Pydantic plugin handling of subclass field overrides is a separate concern (PR #640 partial fix). This docs PR addresses what adopters need today, with the right submodule path for each common case.

Test plan

• `docs/extending-types.md` examples typecheck under `mypy --strict` (verified the listing-slice example separately against an installed adcp 4.6.x)
• Existing example imports updated to point at the correct submodule (no behaviour change in narrative — examples were already conceptually about the listing variant)
• Mermaid / formatting renders cleanly

🤖 Generated with Claude Code